home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / libdl / dlopen.z / dlopen
Encoding:
Text File  |  2002-10-03  |  22.9 KB  |  407 lines

  1. DLOPEN(3C)                                            Last changed: 2-23-99
  2.  
  3.  
  4. NNAAMMEE
  5.      ddllooppeenn, ssggiiddllooppeenn__vveerrssiioonn - Opens a Dynamic Shared Object (DSO)
  6.  
  7. SSYYNNOOPPSSIISS
  8.      cccc [_o_p_t_i_o_n_s ...] _f_i_l_e ...... --llcc [_l_i_b_r_a_r_y ......]
  9.  
  10.      ##iinncclluuddee <<ddllffccnn..hh>>       (Required for both ddllooppeenn and for
  11.                               ssggiiddllooppeenn__vveerrssiioonn)
  12.  
  13.      ##iinncclluuddee <<eellff..hh>>         (Required for ssggiiddllooppeenn__vveerrssiioonn only)
  14.  
  15.      vvooiidd **ddllooppeenn((ccoonnsstt cchhaarr **_p_a_t_h_n_a_m_e,, iinntt _m_o_d_e_1 [ || _m_o_d_e_2 ]));;
  16.  
  17.      vvooiidd **ssggiiddllooppeenn__vveerrssiioonn((ccoonnsstt cchhaarr **_p_a_t_h_n_a_m_e,, iinntt _m_o_d_e_1 [ || _m_o_d_e_2 ],,
  18.           ccoonnsstt cchhaarr **_v_e_r_s_i_o_n,, iinntt _f_l_a_g_s));;
  19.  
  20. IIMMPPLLEEMMEENNTTAATTIIOONN
  21.      IRIX systems
  22.  
  23. DDEESSCCRRIIPPTTIIOONN
  24.      ddllooppeenn and ssggiiddllooppeenn__vveerrssiioonn belong to a family of routines that
  25.      provides direct access to the dynamic linking facilities.  These
  26.      routines are available in a library that is loaded if the --llcc option
  27.      is used with the CCCC(1), cccc(1), ff9900(1), ff7777(1), or lldd(1) command lines.
  28.  
  29.      ddllooppeenn makes a shared object available to a running process.  It
  30.      returns a handle to the process, which the process can use on
  31.      subsequent calls to ddllssyymm(3C) and ddllcclloossee(3C).  This handle should not
  32.      be interpreted in any way by the process.
  33.  
  34.      ssggiiddllooppeenn__vveerrssiioonn dynamically loads DSOs in a way similar to ddllooppeenn.
  35.      However, unlike ddllooppeenn, the interface version of the DSO is specified
  36.      (on the _v_e_r_s_i_o_n and _f_l_a_g_s arguments) so that the dynamic linker tries
  37.      to map in the DSO with the matching interface version.  Aside from the
  38.      restriction to a particular DSO _v_e_r_s_i_o_n, the effect of
  39.      ssggiiddllooppeenn__vveerrssiioonn is identical to that of ddllooppeenn.
  40.  
  41.      These routines accept the following arguments:
  42.  
  43.      _p_a_t_h_n_a_m_e  Specifies the path name of the object to be opened.  It can
  44.                be an absolute path or it can be relative to the current
  45.                directory.  If the value of _p_a_t_h_n_a_m_e is 0, ddllooppeenn makes the
  46.                symbols contained in the original aa..oouutt file, and all of the
  47.                objects that were loaded at program startup with the aa..oouutt
  48.                file, available through ddllssyymm(3C).
  49.  
  50.      _m_o_d_e_1     Specifies when relocations can occur.  This is the primary
  51.                mode.
  52.  
  53.                When a DSO is brought into the address space of a process,
  54.                it might contain references to symbols whose addresses are
  55.                not known until the object is loaded.  These references must
  56.                be relocated before the symbols can be accessed.  _m_o_d_e_1
  57.                governs when these relocations occur.
  58.  
  59.                Specify either RRTTLLDD__LLAAZZYY or RRTTLLDD__NNOOWW for _m_o_d_e_1, as follows:
  60.  
  61.                _m_o_d_e_1          AArrgguummeenntt
  62.  
  63.                RRTTLLDD__LLAAZZYY      Specifies that only references to data
  64.                               symbols are relocated when the object is
  65.                               loaded.  References to functions are not
  66.                               relocated until a given function is invoked
  67.                               for the first time.  This _m_o_d_e should result
  68.                               in the best performance because a process
  69.                               cannot reference all of the functions in any
  70.                               given shared object.
  71.  
  72.                RRTTLLDD__NNOOWW       Specifies that all necessary relocations are
  73.                               performed when the object is first loaded.
  74.                               This might result in some wasted effort if
  75.                               relocations are performed for functions that
  76.                               are never referenced, but it is useful for
  77.                               programs that need to know as soon as an
  78.                               object is loaded that all symbols referenced
  79.                               during execution are available.
  80.  
  81.      _m_o_d_e_2     Refines the _m_o_d_e_1 specification.  This is the secondary
  82.                mode.  You must include a _m_o_d_e_1 specification in order to
  83.                specify a _m_o_d_e_2.  The _m_o_d_e_2 argument must be preceded by an
  84.                OR bar (||).
  85.  
  86.                Specify either RRTTLLDD__GGLLOOBBAALL or RRTTLLDD__LLOOCCAALL for _m_o_d_e_2.  If
  87.                _m_o_d_e_2 is not specified, RRTTLLDD__LLOOCCAALL is assumed.  The _m_o_d_e_2
  88.                specifications are as follows:
  89.  
  90.                _m_o_d_e_2          AArrgguummeenntt
  91.  
  92.                RRTTLLDD__GGLLOOBBAALL    Modifies the treatment of the symbols in the
  93.                               DSO being opened to be identical to those of
  94.                               ssggiiddllaadddd(3C).  With RRTTLLDD__GGLLOOBBAALL, the returned
  95.                               handle is less necessary than without
  96.                               RRTTLLDD__GGLLOOBBAALL because rrlldd(5) directly resolves
  97.                               references to symbols when RRTTLLDD__GGLLOOBBAALL is
  98.                               specified and ddllssyymm(3C) is not needed.
  99.  
  100.                RRTTLLDD__LLOOCCAALL     Specifies that symbols in the DSO are not
  101.                               made globally visible.  Default.
  102.  
  103.                For more information on the effects of RRTTLLDD__GGLLOOBBAALL and
  104.                RRTTLLDD__LLOOCCAALL, see the NNAAMMEESSPPAACCEE IISSSSUUEESS and SSYYMMBBOOLL VVIISSIIBBIILLIITTYY
  105.                sections of this man page.
  106.  
  107.      _v_e_r_s_i_o_n   Specify a string that identifies the software version
  108.                number.  For more information on _v_e_r_s_i_o_n strings, see the
  109.                lldd(1) man page and the _H_o_w _a_r_e _m_u_l_t_i_p_l_e _v_e_r_s_i_o_n_s _o_f _D_S_O_s
  110.                _s_u_p_p_o_r_t_e_d? question on the ddssoo(5) man page.
  111.  
  112.                The _v_e_r_s_i_o_n should be a single version, such as ssggii22..00.
  113.                Multiple versions are not accepted, meaning ssggii22..00::ssggii22..11 is
  114.                incorrect as a value of the version string.
  115.  
  116.                While the effect of passing multiple versions in the string
  117.                is undefined, the effect has been to treat ssggii22..00::ssggii22..11 as
  118.                if it were ssggii22..00, unless LLLL__RREEQQUUIIRREE__MMIINNOORR was set in the
  119.                _f_l_a_g_s argument.  If multiple versions are in the _v_e_r_s_i_o_n
  120.                argument, and LLLL__RREEQQUUIIRREE__MMIINNOORR is in the _f_l_a_g_s argument,
  121.                version matching fails.
  122.  
  123.      _f_l_a_g_s     Specify either LLLL__NNOONNEE or LLLL__RREEQQUUIIRREE__MMIINNOORR.
  124.  
  125.                Specifying LLLL__NNOONNEE means that the exact version must be
  126.                present, but the minor version number is ignored in
  127.                comparisons.
  128.  
  129.                Specifying LLLL__RREEQQUUIIRREE__MMIINNOORR means that only that precise
  130.                major and minor version are accepted.
  131.  
  132.    NNAAMMEESSPPAACCEE IISSSSUUEESS
  133.      This section does not address symbol resolution from ddllssyymm(3C).  For
  134.      details on its symbol resolution rules, see the ddllssyymm(3C) man page.
  135.  
  136.      Name resolution can become surprisingly complicated and nonintuitive
  137.      in the presence of programs or DSOs that use ddllooppeenn, ssggiiddllaadddd(3C),
  138.      ssggiiddllooppeenn__vveerrssiioonn, or LLLL__DDEELLAAYY__LLOOAADD (the --ddeellaayy__llooaadd option to the
  139.      lldd(1) command).
  140.  
  141.      If there is only one definition of a symbol across all loaded DSOs,
  142.      that definition is used if it is visible.  For more information on
  143.      visibility, see the SSYYMMBBOOLL VVIISSIIBBIILLIITTYY section of this man page.
  144.  
  145.      Name searches are done in the order of a single list, called the
  146.      _r_l_d-_l_i_s_t.  The first rld-list entry is the program itself.  Following
  147.      that is the list of DSOs currently in the runtime of the program.  At
  148.      program startup, a breadth-first list of DSOs in the program (and,
  149.      recursively their library lists) is formed in the rld-list.  No DSO is
  150.      added to the rld-list twice.  If there is a later occurrence of a DSO,
  151.      the earlier occurrence is used.  For an exception, see the NNOOTTEESS
  152.      section of this man page.  For any DSO library list entry marked
  153.      LLLL__DDEELLAAYY__LLOOAADD, the referenced DSO is not loaded at program startup.
  154.  
  155.      An exception to the name search rule is made if a DSO is marked as
  156.      DDTT__SSYYMMBBOOLLIICC.  In this case, all name searches from within that DSO
  157.      begin at the DSO itself and continue with the standard rld-list
  158.      search.  For more information on this, see the --BBssyymmbboolliicc option to
  159.      the lldd(1) command.
  160.  
  161.      When, as a result of a call to a function in a DSO that has been
  162.      loaded by using LLLL__DDEELLAAYY__LLOOAADD, that DSO is loaded and the new DSO is
  163.      added at the end of the rld-list.  If it has any entries in its
  164.      library list that are not marked LLLL__DDEELLAAYY__LLOOAADD, the DSOs that are not
  165.      delay-loaded are added recursively (breadth-first).  Depending on the
  166.      order of calls to delay-loaded DSOs, the order of DSOs on the rld-list
  167.      might be different from one run of a program to the next.
  168.  
  169.      The order of DSOs in the rld-list might not match the order in any
  170.      given library list because if a DSO is already in the rld-list, it is
  171.      not added a second time to the rld-list.
  172.  
  173.      As a result of the rule that the search order is in rld-list order,
  174.      the symbol that is found can be surprising.  Consider a symbol AA found
  175.      in DSOs BB and CC.  Further, DSO BB is before DSO CC in EE's library list
  176.      while DSO BB is after DSO CC in FF's library list.  Neither DSO BB nor DSO
  177.      CC are otherwise referenced.  If DSO EE is opened by using ddllooppeenn with a
  178.      _m_o_d_e of RRTTLLDD__GGLLOOBBAALL and it is opened before DSO FF, the AA from DSO BB is
  179.      found by ddllssyymm(3C) from either handle.  Similarly, if DSO FF is opened
  180.      by using ddllooppeenn with a _m_o_d_e of RRTTLLDD__GGLLOOBBAALL and it is opened before DSO
  181.      EE, the AA from DSO CC is found by ddllssyymm(3C) from either handle.
  182.      However, if only one of the DSOs EE or FF is opened by using ddllooppeenn with
  183.      a _m_o_d_e of RRTTLLDD__GGLLOOBBAALL, one gets DSO BB's AA from DSO EE's handle and one
  184.      gets DSO CC's AA from DSO FF's handle.
  185.  
  186.      Note that ddllcclloossee(3C) does not cause any reordering of the rld-list.
  187.      When the last handle (direct or indirect) on a DSO is closed with
  188.      ddllcclloossee(3C), the DSO is removed from the rld-list.  Before the final
  189.      ddllcclloossee(3C), the DSO remains where it was on the rld-list.
  190.  
  191. SSYYMMBBOOLL VVIISSIIBBIILLIITTYY
  192.      DSOs loaded by a single invocation of ddllooppeenn can import symbols from
  193.      one another or from any DSO that is globally visible, but DSOs loaded
  194.      by one ddllooppeenn invocation cannot directly reference symbols from DSOs
  195.      loaded by a different ddllooppeenn invocation.  You can reference those
  196.      symbols indirectly, however, by using ddllssyymm(3C).
  197.  
  198.      Globally visible DSOs are those added at program startup or via
  199.      delay-load from a globally-visible object.  In addition, any DSO added
  200.      by ssggiiddllaadddd(3C), by ddllooppeenn with a _m_o_d_e of RRTTLLDD__GGLLOOBBAALL, or by
  201.      ssggiiddllooppeenn__vveerrssiioonn with a _m_o_d_e of RRTTLLDD__GGLLOOBBAALL is globally visible.
  202.      DSOs opened with RRTTLLDD__LLOOCCAALL are not globally visible.
  203.  
  204.      Even in a globally visible DSO, a symbol is invisible to any access
  205.      from outside the DSO if the symbol is marked SSTTOO__HHIIDDDDEENN; for an
  206.      example of this see the lldd(1) man page's descriptions for the
  207.      --hhiiddddeenn__ssyymmbbooll or --hhiiddeess__ffiillee options.  From within a DSO, all symbols
  208.      in that DSO are visible.  From within a DSO, all globally visible
  209.      symbols are visible.
  210.  
  211.      Consider the following set of DSOs:
  212.  
  213.           ld -shared -all F.a -o F.so
  214.           ld -shared -all G.a -o G.so
  215.           ld -shared -all E.a F.so G.so -o E.so
  216.           ld -shared -all H.a F.so  -o H.so
  217.  
  218.      Consider the following conditions:
  219.  
  220.      * A program contains ddllooppeenn((""EE..ssoo"",,RRTTLLDD__LLAAZZYY)) and
  221.        ddllooppeenn((""HH..ssoo"",,RRTTLLDD__LLAAZZYY)).
  222.  
  223.      * The program uses ddllssyymm to find functions through the two handles and
  224.        calls these two functions.
  225.  
  226.      * Each of these calls a function that calls ffff(()) in FF..ssoo.
  227.  
  228.      * ffff(()) calls ffgg(()), which is defined only in GG..ssoo.
  229.  
  230.      Logically, you could assume that the call through the function
  231.      accessed via EE..ssoo would resolve to ffgg(()) in GG..ssoo and that the call
  232.      through the function accessed via HH..ssoo would result in an undefined
  233.      function.  However, rrlldd(5) does not attempt to determine (by walking
  234.      the run-time stack or other means) the exact call stack to ffff(()). The
  235.      call stack is not really enough; rrlldd(5) needs to know the handle used
  236.      to derive the calls.  The result of the call to ffgg(()) is undefined.
  237.      What happens is that ffgg(()) in GG..ssoo is called, since such would be legal
  238.      if the call path were through the handle in EE..ssoo.  It is unwise to
  239.      depend on such behavior.
  240.  
  241. SSEEAARRCCHHIINNGG FFOORR DDSSOOss
  242.      If other DSOs were link edited with _p_a_t_h_n_a_m_e when _p_a_t_h_n_a_m_e was built,
  243.      those objects are automatically loaded by ddllooppeenn.  This is subject to
  244.      the LLLL__DDEELLAAYY__LLOOAADD library list flag.  The directory search path that
  245.      is used to find both _p_a_t_h_n_a_m_e and the other needed objects is the same
  246.      as that used by rrlldd(5).  In particular, _p_a_t_h_n_a_m_e is searched for in
  247.      the following locations:
  248.  
  249.      * The directory specified by _p_a_t_h_n_a_m_e if it is not a simple file name
  250.        (that is, it contains a slash (//) character).  If it is not a simple
  251.        file, _p_a_t_h_n_a_m_e is the only location searched; the other locations
  252.        are ignored.
  253.  
  254.      * Any path specified via the --rrppaatthh argument to lldd(1) when the
  255.        executable file was statically linked.
  256.  
  257.      * Any directory specified by the LLDD__LLIIBBRRAARRYY__PPAATTHH environment variable.
  258.        This environment variable should contain a colon-separated list of
  259.        directories, in the same format as the PPAATTHH variable (see sshh(1)).
  260.        64-bit programs examine the LLDD__LLIIBBRRAARRYY6644__PPAATTHH variable, and if it is
  261.        not set, they examine the LLDD__LLIIBBRRAARRYY__PPAATTHH variable.  New 32-bit ABI
  262.        programs examine the LLDD__LLIIBBRRAARRYYNN3322__PPAATTHH variable and if it is not
  263.        set, they examine the LLDD__LLIIBBRRAARRYY__PPAATTHH variable.
  264.  
  265.        All of these variables are ignored if the process is running sseettuuiidd
  266.        or sseettggiidd (see eexxeecc(2)).
  267.  
  268.      * The default search paths.  The paths differ depending on ABI.  For
  269.        information on the specific search paths, see the rrlldd(5) man page.
  270.  
  271.      If the process is running sseettuuiidd or sseettggiidd, the __RRLLDD__RROOOOTT,
  272.      __RRLLDDNN3322__RROOOOTT, or __RRLLDD6644__RROOOOTT variable (the exact variable name depends
  273.      on the ABI being used) is ignored (see rrlldd(5)).
  274.  
  275. NNOOTTEESS
  276.      You can open objects whose names resolve to the same absolute or
  277.      relative path name any number of times by using ddllooppeenn.  However, the
  278.      referenced object is loaded only once into the address space of the
  279.      current process.  The same object referenced by two different path
  280.      names, however, can be loaded multiple times.  For example, given the
  281.      object //uussrr//hhoommee//mmee//mmyylliibbss//mmyylliibb..ssoo, and assuming the current working
  282.      directory is //uussrr//hhoommee//mmee//wwoorrkkddiirr, the following code results in
  283.      mmyylliibbss..ssoo being loaded twice for the current process:
  284.  
  285.           ...
  286.           void *handle1;
  287.           void *handle2;
  288.  
  289.           handle1 = dlopen("../mylibs/mylib.so", RTLD_LAZY);
  290.           handle2 = dlopen("/usr/home/me/mylibs/mylib.so", RTLD_LAZY);
  291.           ...
  292.  
  293.      On the other hand, given the same object and current working
  294.      directory, if LLDD__LLIIBBRRAARRYY__PPAATTHH==//uussrr//hhoommee//mmee//mmyylliibbss, the following code
  295.      results in mmyylliibbss..ssoo being loaded only once:
  296.  
  297.           ...
  298.           void *handle1;
  299.           void *handle2;
  300.  
  301.           handle1 = dlopen("mylib.so", RTLD_LAZY);
  302.           handle2 = dlopen("/usr/home/me/mylibs/mylib.so", RTLD_LAZY);
  303.           ...
  304.  
  305.      Users who use ddllssyymm((00,,mmooddee)) to gain access to the symbol table of the
  306.      aa..oouutt file itself should be aware that some symbols defined in the
  307.      aa..oouutt file might not be available to the dynamic linker.  The symbol
  308.      table created by lldd(1) for use by the dynamic linker might contain
  309.      only a subset of the symbols defined in the aa..oouutt file, specifically
  310.      those referenced by the shared objects with which the aa..oouutt file is
  311.      linked.
  312.  
  313.      Because there is no defined mechanism for dynamic loading in nonshared
  314.      programs, a program built as nonshared (for example, by using cccc
  315.      --nnoonn__sshhaarreedd) cannot usefully call ddllooppeenn, ddllssyymm(3C), ddlleerrrroorr(3C),
  316.      ssggiiddllooppeenn__vveerrssiioonn, ssggiiddllaadddd(3C), or ddllcclloossee(3C).  The dynamic loading
  317.      routines are not included in the nonshared lliibbcc..aa file, so attempting
  318.      to use them might result in a failure at link time.  Any program built
  319.      as nonshared that wishes to retain code that calls the dynamic loading
  320.      routines must implement its own versions of ddllooppeenn, ddllssyymm(3C), and so
  321.      on, and simply return appropriate error values to avoid the link-time
  322.      errors.  Note that building programs as nonshared is not generally
  323.      recommended because not all libraries are available as nonshared.
  324.  
  325.      Using ddllcclloossee(3C) on a DSO, with __RRLLDD__AARRGGSS set to --ss in the
  326.      environment, can cause surprising side effects.  This is because
  327.      ddllcclloossee(3C) forces many symbol GOT entries to be reset for
  328.      re-lazy-evaluation.  A result of this is that function pointers
  329.      previously saved by the application or some library might hold values
  330.      that could be obsolete or no longer correct.  This is a problem for
  331.      any ddllcclloossee(3C) process, but it is more serious when ddllcclloossee(3C) is
  332.      used to close a handle on a globally-visible DSO.
  333.  
  334.      Symbol lookups proceed in order on a linear list, and a DSO is not
  335.      opened twice with the same version number (unless different ddllooppeenn
  336.      paths make the DSO name appear different to rrlldd(5)).  When multiple
  337.      ssggiiddllaadddd(3C) processes are executed and ddllcclloossee(3C) is used to close
  338.      an earlier DSO, this can change the symbol to which a call is
  339.      resolved.  For more information, see the NNAAMMEESSPPAACCEE IISSSSUUEESS section.
  340.  
  341. EEXXAAMMPPLLEESS
  342.      The following specifies the RRTTLLDD__LLAAZZYY and RRTTLLDD__LLOOCCAALL modes:
  343.  
  344.           dlopen("X.so",RTLD_LAZY|RTLD_LOCAL);
  345.  
  346.      The following example program uses ddllooppeenn and was compiled with the
  347.      --3322 compiler command line option:
  348.  
  349.           dltry.c:
  350.           -------
  351.           /* Error handling code not shown.
  352.           */
  353.           #include <dlfcn.h>
  354.  
  355.           typedef int (*xamplefuncptr)(int);
  356.           int main()
  357.           {
  358.              void *handle;
  359.              int   i;
  360.              xamplefuncptr fptr;
  361.  
  362.              handle = dlopen("greetings.so", RTLD_LAZY|RTLD_LOCAL);
  363.              fptr = (xamplefuncptr)dlsym(handle, "greetings");
  364.              i = (*fptr)(3);
  365.              return 0;
  366.           }
  367.  
  368.           greetings.c:
  369.           -----------
  370.           #include <stdio.h>
  371.           int greetings(int num_greetings)
  372.           {
  373.              int i;
  374.  
  375.              for (i=0; i < num_greetings; i++)
  376.                 printf ("hello world\n");
  377.              return 1;
  378.           }
  379.  
  380.  
  381.           % cc -32 -c dltry.c greetings.c
  382.           % ld -32 -shared greetings.o -soname greetings.so -o greetings.so
  383.           % cc -32 dltry.o
  384.           % LD_LIBRARY_PATH=.
  385.           % export LD_LIBRARY_PATH
  386.           % a.out
  387.           hello world
  388.           hello world
  389.           hello world
  390.  
  391. RREETTUURRNN VVAALLUUEESS
  392.      If _p_a_t_h_n_a_m_e cannot be found, cannot be opened for reading, is not a
  393.      DSO, or if an error occurs during the process of loading _p_a_t_h_n_a_m_e or
  394.      relocating its symbolic references, ddllooppeenn returns NNUULLLL.  More
  395.      detailed diagnostic information is available through ddlleerrrroorr(3C).
  396.  
  397. SSEEEE AALLSSOO
  398.      CCCC(1), cccc(1), ff7777(1), ff9900(1), lldd(1), sshh(1)
  399.  
  400.      eexxeecc(2)
  401.  
  402.      ddllcclloossee(3C), ddlleerrrroorr(3C), ddllssyymm(3C), ssggiiddllaadddd(3C),
  403.  
  404.      ddssoo(5), rrlldd(5)
  405.  
  406.      This man page is available only online.
  407.